The “Other View Systems” folder in ODF is an add-on to support the MetroWerks Constructor view editor. It enables your part to read the PowerPlant view format and create equivalent ODF views, so you can build your user interface using a visual tool.
There are two main benefits to using Constructor to do view editing:
• Faster User Interface Development
A view editor enables you to experiment with view layouts much more easily than by editing text-based descriptions (the standard ODF approach). Also, because there is no intermediate compiling step, views can be edited and reloaded while the part is still running.
• Code Migration
This provides an extra step in moving from applications to parts. You can now move PowerPlant-based application code to PowerPart, and from there to ODF to gain cross-platform capability without having to change the user interface very much. The application code itself must still be converted manually, however being able to reuse the same views does help.
The add-on works with the current ODF 1 release. No changes to the framework classes were necessary, all the code doing the resource parsing is isolated in a few files.
The main idea is to parse the resource stream the same way the PowerPlant code does. For each view, the data is read in and converted as necessary (for example, integers to fixed point, text trait handles to ink objects). Then an equivalent ODF view object is created.
Using this add-on in any part is only a matter of adding the Constructor View Parser support files and overriding a single method to call the support code instead of the ODFRC view reading code. If you use custom views you will need to add code to create them as well.
There are two main limitations to the Constructor support:
• The ODF view system only supports one scroller per frame; only the “content” view can scroll. There are ways to handle additional scrollers for situations like secondary text fields (see ODFForm for an example).
• ODF doesn’t have as extensive a set of view classes as does Constructor. The gridview class, for instance, isn’t yet official and isn’t supported by this add-on.
Changes Since Release 2
More view classes have been added since R2. There is a new FW_CGraphicControl for artwork and graphic controls. A new FW_CIncludeView can include views from other resources. And the PPob reader has been rewritten since ODF R2, making custom view types much easier to support.
FW_CGraphicControl
Many view systems have a large number of classes to deal with “artwork,” like icons and picture buttons. ODF now has a single view class, FW_CGraphicControl, which handles this job. It uses shape objects, part of ODF’s cross-platform object-oriented graphics engine, to represent artwork graphics. FW_CGraphicControl can have up to 4 shape objects to represent different states: normal, “on”, pushed-normal and pushed-”on”.
FW_CGraphicControl is created automatically for you when the PPob reader encounters LTextButton, LButton, LToggleButton, or LIconPane. LCicnButton is not supported because the ODF graphics engine only supports ‘icxx’ icon families, not the older ‘cicn’ color icon type.
ODFForm’s content view contains two graphic control views (the OpenDoc™ and ODF icons).
FW_CIncludeView
FW_CIncludeView is a “placeholder” view - it is placed in a view hierarchy, and when loaded will include a second view hierachy from a different resource. This should greatly simplify the creation of root frame, embedded frame, and printing frame hierarchies. Now you can have three “root” hierarchies with various combinations of scrollbars and rulers, and have all three include the main content views from a fourth, independent resource. See ODFForm’s PPView.ppob for an example.
To use FW_CIncludeView in Constructor, you need to copy the custom pane type definition from FWPPObs.rsrc, which is in the “PowerPlant PPob” folder (in the “Other View Systems” folder in ODF).
Here’s how you would go about laying out your view hierarchies.
Root Frame: Create a new view resource in Contstructor and use a window at the top. Put a scroller in it (if you need scrolling or a content view). Then put an FW_CIncludeView inside the scroller. Make sure to give the scroller the ID# of your content view (ODFForm uses 100), and give the include view the ID of your content view resource (ODFForm uses 1000).
Content view: Create this without a window at the top. ODFForm uses a CFormView (LPicture subclass) at the top. You can do this by dragging your view off of the view palette into the catalog window. You can also use the New Window Resource menu item and choose LView from the view type popup if you don’t need a special subclass. Make sure the view hierarchy has the correct resource ID (e.g. 1000 in ODFForm), and if you are using a content view, give it your content ID# (e.g. 100 in ODFForm).
Getting views aligned properly can be a challenge. Make sure your include view and included view have the same dimensions.
Custom View Types (Enhancing the PPob Reader)
Custom pane types used to require defining a subclass and several methods. Now you only need to write one method. Here are two examples from ODFForm, a password view and a content view.
• Password Text View
ODFForm has a subclass of FW_CEditView called CPwdEditView. In Constructor, this view is defined by using an LEditField with a class ID of ‘PwEd’. It doesn’t have any extra fields.
The view class is registered in CFormPart::Initialize:
ODFForm’s content view, CFormView, is a subclass of FW_CPictSView. It adds a field for a second picture resource ID. In Constructor, ODFForm has a custom pane type definition which inherits from LPicture and has a class ID of ‘Frmv’.
The view class is registered in CFormPart::Initialize:
// CFormView is capable of having subviews, so tell the PPob reader
context->SetNextSuperView (view);
}
PowerPlant views are archived in much the same way as ODF views, so reading them in is easy. In this case, LPicture is a subclass of LView. FWPPobOb.h and FWPPobOb.cpp contain a utility class for reading in LView data, but not for LPicture. Since the LPicture data is just one single resource ID after the inherited LView data, we can use the LView utility class (FW_SPPobViewInfo) and then read the resource ID. After that, we defined CFormView to have one resource ID, which we also read.
The final step after creating the view is to deal with subviews. Any view which might have subviews must call the PPob reader’s SetNextSuperView to set things up. If you forget, any subviews will be placed inside the current superview (the parent of this view) and will be located relative to its upper left corner.
Adding Constructor Support to Your Part
We assume here that you have already started to build your part’s user interface with Constructor, or that you are re-using existing view resources. This section explains how to put things together in your project and modify your source code in order to use these views. All code samples are taken from ODFForm.
Follow these steps:
1) Add the view resource file to your project
The view reloading code (see below) assumes the file is called “PPViews.ppob”. If you don’t care about live view reloading, you can give the file any name you wish.
2) Add the PPob reader source and other support files to your project
You will need to add FWPPobRd.cpp and FWPPobOb.cpp to your project. These are located in the “ODF : Other View Systems : PowerPlant PPob” folder. You also need FWScrlVw.cpp if you wish to use LScroller (you probably do), and FWPPobMn.cpp and FWMacMnu.cpp if you want to use Constructor to edit Mac OS-format menu resources.
3) Add the class registrations in your part's Initialize() method
FW_CPPobReader::RegisterAllPPClasses();
Custom view types require separate registration as described above. For example:
4) Pass 0 for the view resource IDs in your call to RegisterPresentation.
Check that your part’s call to RegisterPresentation is not passing a view id for root or embedded frames. Doing so would make ODF try to load the native ODFRC resource with that id instead of calling the frame’s CreateSubViews method, which is what we need.
This is where you tell ODF to use the PPob Reader module instead of loading native ODF resources.
void CFormFrame::CreateSubViews(Environment* ev)
{
FW_CPPobReader::CreateViews (ev,
kFormView, // 'PPob' view id
this, // frame is the root view
this, // frame is receiver for all controls
);
}
The 3rd parameter is "this" in order to make the frame the root view of the views being loaded (it could be another superview if one already existed.)
The 4th parameter is usually"this" too in order to make the frame the receiver for all controls being loaded. This avoids having to make an extra call to FW_CPPobReader::LinkReceiverToControls after loading the views. Use a NULL argument if you don't want to link controls automatically. You can also call LinkReceiverToControls afterward and pass a different receiver.
CreateViews may throw an exception (for a missing icon resource, for example). The debug version will catch these and warn you.
6) Add code to support custom classes, including your frame's content view.
When your frame uses a separate content view (like CFormView in Form) or when it needs to use other custom view classes (like CScrollEdit in Form) you must define the mapping between these ODF classes and the PowerPlant classes used in the part's UI. Basically you need a little extra code to extend the PPob reader module in order to have the right conversion done at load time. See the discussion on custom views in the section on Form above.
IMPORTANT: Remember that an ODF frame can use only one scrolling view for its content (the content view). If your UI doesn't contain any scrollers the frame remains the content view. Otherwise the first scrolling view is converted into the content view and additional scrollers will generate a warning and be ignored by ODF. However there are ways to handle standard scrolling views such as text-edit and list boxes. See how this is done in Form.
7) Add the "Reload Views" menu command if necessary
Having a "Reload Views" command is useful in debug mode while you are developing your part and adjusting its interface. See how this is implemented in Form.
The ReloadViews method takes the same arguments as CreateViews:
This command opens the “:Sources:PPViews.ppob” file in the same location as the part; you can also look at the implementation of ReloadViews and write a similar method (it’s small).
WARNING: ReloadViews starts by calling FW_CFrame::DeleteAndResetViews to delete all the frame's subviews and then it calls CreateViews to load the views again. In general your part shouldn't be affected by this operation, i.e. it should be the same as if the views were created for the first time when the frame was created. However the destruction of views may have side effects in your code that you will have to deal with.
8) Build and test
The main sources of problems will be one of the following:
• Your part launches and then quits again.
Probably an exception was thrown during view creation. Make sure to compile a Debug version of the project to work out all errors.
• Your part launches but crashes when the frame is created.
Probably you under- or over-read data from the stream. Step through all of your custom view type functions to make sure you are reading all the PowerPlant fields correctly.
Additional Notes
• It is possible to use more than one view resource kind at a time. You could use ODFRC views for simple frames and only use PPob views for your content frame.
• Using #define flags in order to switch between view systems was done for the sake of the ODFForm example and doesn't reflect normal cases where only one kind of view is used.
• In this release it is not possible to save the converted views back into ODF format in order to avoid linking with the PowerPlant reader code. This may be added in the future.
• PICT resources (for Picture views) and MENU resources (for popup menus) must be present in the current resource file.
Runtime View Editing
It is very convenient to have "live" view editing - that is, to be able to edit your view hierarchy in the view editor and see then changes in your part without having to recompile it. The FW_CPPobReader class has utility methods to support this.
To use it:
• Name your view resource file “PPViews.ppob” (sorry, this is hard-coded into the PPob reader).
• Add a menu item to your part called "Reload Views". In your menu handling code in your frame call FW_CPPobReader::RecreateViews (ev, viewID, superview, receiver). For example:
You should of course still include your views resource file in the project. These will be used whenever the part creates a frame (i.e. whenever you open your document), so you will only get the updated views after calling the RecreateViews method, or relinking your part.
The "Reload Views" command will be modified in the next release so that it can find the <part>.rsrc or <part>.ppob resource file by default in the Sources folder where it generally resides.
The "Reload Views" command doesn’t restore the scrollbars properly. The effect is only cosmetic; they still work. The problem won’t be present for normally-loaded views.
Supported View Classes
The following class conversion occurs when reading a PPob resource:
Any unknown classes will result in dropping into the debugger. To support custom classes, see the “Changes Since Release 2:Custom View Types” section on writing and registering custom view type functions.
Conversion Rules and Limitations
ODF views are restricted to 16-bit coordinates. When reading coordinates or sizes greater than 16 bits the PPob reader gives a debugger warning.
LAttachment classes in the stream are not supported.
LPane classes have the following conversion rules and limitations:
(class fields are named as they appear in the Constructor's class editors)
• LPane fields:
Binding flags and Pane ID are converted.
User Constant field, Enabled and Visible flags are ignored.
• LView fields:
Scroll Unit and Scroll Position are ignored.
Image Size is ignored. Only the content view in ODF has an extent different than its physical size.
When an LView object is a scroller's scrolling view its bounds are changed to match the scroller's bounds (minus the scroll bars) and its binding flags are set the the scroller's binding flags.
• LScroller fields:
An ODF frame can use only one scrolling view for its content (the content view). The first scrolling view is converted into the content view and additional scrollers generate a warning and are ignored by ODF. (However you can handle scrolling views as custom views like CScrollEdit in Form.)
Also you must use an LScroller to specify which view is to be the content view. This can be a problem for printing frames, which don’t need scrollbars, so see ODFForm, which has a scroller in its printing frame but places it so the scrollbars aren’t visible.
The LScroller object itself is converted into an ODF FW_CScrollerView and 1 or 2 scrollbars are created. Their view ids are hard-coded to 'horz' and 'vert'.
• LStdControl fields:
Title, Value Message, Initial Value and Text Traits are converted. Control Ref Con is ignored.
IMPORTANT: the Value Message should be the ODF value. For instance a button should use -10 (FW_kButtonPressedMsg) if you want to use the default ODF notification. Of course you can also use your own message values.
• LWindow fields:
The only data converted from an LWindow object is its location and the presence of a grow box. (A grow box is always created in the bottom right corner of the frame and its view id is hard-coded to 'grow'.) The type of window cannot be used here because the frame's window already exists when its subviews are created.
• LDialogBox fields:
Same as LWindow + the default and cancel button ids. The type of dialog window must be set by program in NewModalDialog().
• LListBox fields:
Horizontal Scrollbar and LDEF ID are not supported. Single selection is the default.
• LEditField fields:
Key filter is not supported.
• LTextEdit fields:
This class is mapped to the same ODF FW_CEditView class as LEditField, because ODF doesn't have any built-in scrolling text class yet. However, ODFForm provides an example custom CScrollEdit class.
• LPicture fields:
The image size should remain 0, 0 in order to use the picture size by default.
The PICT resource must be present in the same resource file.
Menu Support
ODF contains support for menu and menu bar resources edited in MetroWerks Constructor. These are the standard Mac OS resource formats, plus a side table for the command numbers. There are four files that provide support for menus:
FWPPobMn.h, FWPPobMn.cpp
FWMacMnu.h, FWMacMnu.cpp
FWPPobMn.h declares two functions that you can call in your part to create menus from PowerPlant menu resources. These functions are described below.
FWMacMnu.h and FWMacMnu.cpp contain helper classes that read and store data from the resource types 'MBAR', 'MENU', and 'Mcmd'. The 'MBAR' resource contains a list of menu resource IDs. The 'Mcmd' resource type contains a list of command numbers for a single menu.
This function reads a Macintosh menubar resource, then reads the menu resources listed in that resource. The resource data is converted into ODF menus and added to the specified menu bar.
If a menu resource is an Apple menu, it is not added to the menu bar. Instead, the first item string in the Apple menu is used to set the command string for the OpenDoc About command.
The best place to call this function is in an override of FW_CPart::InstallMenus. See the sample code below.
